REST Reference Builder

REST Reference Builder

IN THIS PAGE

Creating a REST Reference
Overview of the Edit REST Service Definition dialog
- Properties
REST Reference Genie
Example: Building a REST Reference using the Random Useless Facts API
- Creating the REST Reference

Description

The REST Reference Builder is used to define endpoints, authentication requirements, and more for querying a third-party REST API.

Discussion

The REST Reference Builder creates an Xbasic class that can be used to make API calls against a third-party REST service in a server-side script. Scripts to query the API are inserted into server-side code using the REST Reference Genie. The genie generates the code required to call the endpoint configured in the REST Reference. Endpoints, or Actions, are made available as methods of the Xbasic class for the REST Reference.

Creating a REST Reference

To create a REST Reference, select the "Web Services" option on the Web Projects Control Panel. Then click the New button. This opens the New Service Type dialog.

In the REST section, click Create a new definition to consume a REST service to create a new REST Reference.

New Service Type dialog

The REST Reference can be created from an existing Google Service, imported from a Swagger definition, or built from scratch.

Enter Name of REST Reference dialog

To create a REST Reference for a Google service, click the Import Google Service... URL and select the desired Google service. Refer to Google's documentation for the desired API for more information about using the selected API.

Google REST Service Definition Import

Some REST APIs provide a Swagger definition. A Swagger definition is a JSON document that describes a RESTful API. If the API that you'd like to use provides a Swagger definition, you can use the the Import Swagger... link to import the Swagger definition. The Swagger definition can be pasted directly into the window, imported from a URL, or loaded from a local file. Alpha Anywhere will use the definition to generate the REST Reference.

Enter Swagger Definition

After entering a Name, you can click Create to generate the REST Reference. Alpha Anywhere will create a new file with an "a5restapi" extension with the name specified in the Create REST Reference dialog. The Edit REST Service Definition may also automatically open.

Overview of the Edit REST Service Definition dialog

The Edit REST Service Definition dialog contains the REST Reference definition. Included in the definition is the REST API URL, endpoints (Actions), Named Resource Providers, and other information required to call the API.

If you don't import a Google service, the Edit REST Service Definition dialog opens after creating the service.

Edit REST Service Definition

Properties

The Properties tab contains the base URL and Provider information for the API:

Property: Description
Resource URL: The base path for the REST service. E.g. https://www.myservice.com/v1/api/
Public Access - Provider: The API endpoint for endpoints that don't require authentication. Public endpoints may require an API key but generally don't require the user to provide credentials, such as OAuth credentials.
Private Access - Provider: The API endpoint for endpoints that require authentication, such as OAuth.

Endpoints for the REST API are added as Actions. An Action specifies the Path, parameters, the method (GET, POST, etc), and the schema for content sent in the body and header of the request.

You can add an Action using the Add Action button. You can also create an Action by importing from a CURL command via Import from CURL....

Import from CURL

Placeholders can be used where needed in the URL and body using the syntax {placeholder_name}. "placeholder_name" corresponds to the value of Name for a Parameter, defined at the bottom of the dialog using the Add Parameter button. Any headers required by the endpoint are also defined as Parameters.

Edit Action dialog

REST Reference Genie

The REST Reference Genie generates the Xbasic to call an endpoint defined in a REST Reference. The genie is found in the context menu for the Xbasic editor. Right-click anywhere in the Xbasic editor, then select Genies... > REST Reference call....

REST Reference call option in the context menu

Select the REST service in the Service column that you'd like to use, then choose the endpoint to call in the Method column. Alpha Anywhere will display the Xbasic to call the endpoint in the code window at the bottom of the dialog. Click Copy Example to Clipboard to copy the code. When you click OK, the code for the selected method is automatically inserted into the Xbasic editor at the cursor location.

Pick a REST Service and Method dialog

The Generate dropdown box at the top fo the dialog can be used to add help information to the Xbasic in the form of comments.

Example: Building a REST Reference using the Random Useless Facts API

In this example, we'll build a REST Reference for the Random Useless Facts API. The Random Useless Facts API is a free public REST API that returns a random useless fact. The API has two end points: /random, which returns a random useless fact, and /today which returns the useless fact of the day. Facts can be retrieved in German (de) or English (en) in a variety of formats (.html, .json, .txt, or .md). For example, the URL to retrieve a random fact in English as JSON is:

https://uselessfacts.jsph.pl/random.json?language=en

Creating the REST Reference
To create a new REST Reference, select the "Web Services" option on the Web Projects Control Panel. Then click the New button.
When the New Service Type dialog appears, select Create a new definition to consume a REST service in the REST portion of the dialog.
New Service Type dialog
Enter a name for the REST Reference then click Create. In this example, we'll name the REST Reference randomFact.
Enter Name of REST Reference prompt
After creating the REST Reference, Alpha Anywhere opens the reference for editing. The Edit REST Service Definition builder is where you specify the REST API URL, authentication requirements, and endpoints (Actions) that you'd like to call.
Edit REST Service Definition builder
Next, we'll configure the Resource URL for the API. Add the following information to the Edit REST Service Definition builder:
Resource URL
https://uselessfacts.jsph.pl
The Random Useless Fact API does not require authentication, so the Public Access and Private Access properties should be blank.
Now that we've defined the Resource URL, we can add Actions for the /random and /today endpoints. Click the Add Action button to add a new action.
Add Action button
The first action we'll add will call the /today endpoint. Enter the following values in for the corresponding property in the Action editor:
Property
Value
Name
today
Method
get
Access
public
Next, we'll define the Path. Click the smart field button for the Path property. Then, enter the following values in the Path and Query Parameters text boxes:
Property
Value
Path
/today{format}
Query Parameters
language={language}
Defining the Path and Query Parameters
The /today endpoint has two optional parameters you can use to request a specific file format and language to use when returning the fact. The file format is part of the path. For example, /today.json will return the fact in JSON format.
To make the call dynamic, we can specify a placeholder in the path representing the optional format: {format}.
The language is passed to the endpoint as a query parameter. E.g. /today?language=en returns the fact in English. We can use a placeholder, {language}, in the Query Parameters to make the is a placeholder for the requested language.
Click OK to save the Path definition.
After defining the Path, we next need to define the parameters used in the path definition. We'll configure the {language} placeholder first. Alpha Anywhere should automatically add a parameter for language after saving the Path.
Specifying parameters
If there are no parameters listed in the dialog, you can create the language parameter using Add Parameter: click the Add Parameter button to add a parameter, select the Query option, then click OK.
Add a new Query Parameter
Verify that the Query parameter for language has the following values for Name and Location:
Property
Value
Name
language
Location
Query
Next, we'll create the format parameter. Click Add Parameter, select the Path option, then click OK.
Add a new Path Parameter
Select the new path parameter. Then, enter the following values for the Name and Location properties:
Property
Value
Name
format
Location
Path
The complete definition for the today endpoint
When you've finished defining the {format} parameter, you can test the Action. Click Test to open the Action tester
Action test dialog
Enter a language and format in the language and format. The Random Useless Fact API supports the following values for language and format:
Language Options
Description
en
Return the fact in English
de
Return the fact in German
Format Options
Description
.html
Return the fact formatted as HTML.
.json
Return the fact formatted as JSON.
.txt
Return the fact formatted as plain text.
.md
Return the fact formatted as Markdown
The image below shows the result of calling the endpoint with language set to "en" and format set to ".json":
Action test results
When you are done testing the endpoint, click Save to save the Action.
Repeat the process above to add the /random endpoint. The /random endpoint takes the same optional parameters as /today. The Action definition should be identical to /today with the exception of the path portion for the Path parameter, which is defined as /random{format}.
After adding the /random Action, save the REST Service Definition. It can now be added to any Xbasic script using the REST Reference Genie.